[% setvar title Arrays: transpose() %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Arrays: transpose()</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Jeremy Howard &lt;<a href='mailto:j@howard.fm'>j@howard.fm</a>&gt;
  Date: 22 Sep 2000
  Last Modified: 24 Sep 2000
  Mailing List: <a href='mailto:perl6-language-data@perl.org'>perl6-language-data@perl.org</a>
  Number: 272
  Version: 2
  Status: Frozen</pre>
<a name='DISCUSSION'></a><h1>DISCUSSION</h1>
<p>This RFC was modified to incorporate the functionality of PDL's xchg() and
mv(), which are useful for acting on arbitrary dimensions of
multidimensional arrays. Implementing aliasing was discussed in more
detail than for RFCs 90, 91, and 148, including suggestions to learn from
PDL's implementation (outlined in RFC 116), which are more sophisticated
than simply keeping a list of mapped indices, instead actually storing
information about the specific operations that have occured.</p>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>It is proposed that a new function <code>transpose</code> be added to Perl.
<code>transpose($dim1, $dim2, @list)</code> would return @list with $dim1 and $dim2
switched. <code>transpose(\@order, @list)</code> would return @list with dimensions
in the order specified by @order. <code>transpose</code> would return an alias into
the original list, not a copy of the elements.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<a name='Swapping Dimensions'></a><h2>Swapping Dimensions</h2>
<p>It is proposed that Perl implement a function called <code>transpose</code> that
transposes two dimensions of an array, and is evaluated lazily. <i><a href='#RFC 202'>&quot;RFC 202&quot;</a></i>
gives an overview of the proposed multidimensional arrays that
<code>transpose</code> works with. For instance:</p>
<pre>  @a = ([1,2],[3,4],[5,6]);
  @transposed_list = transpose(0,1,@a);   # ([1,3,5],[2,4,6])</pre>
<p>This is different to <code>reshape</code> (see <i><a href='#RFC 148'>&quot;RFC 148&quot;</a></i>) which does not reorder
its elements:</p>
<pre>  @a = ([1,2],[3,4],[5,6]);
  @reshaped_list = reshape([3,2],@a);   # ([1,2,3],[4,5,6])</pre>
<p><code>transpose</code> is its own inverse:</p>
<pre>  @transposed_list = transpose(0,1,@a);   # ([1,3,5],[2,4,6])
  @orig_list = transpose(0,1,@transposed_list); # (([1,2],[3,4],[5,6])
  @a == @orig_list;   # true</pre>
<p>If <code>transpose</code> refers to a dimension that does not exist, empty
dimensions autovivify as necessary:</p>
<pre>  @row_vector = (1,2,3,4);
  @col_vector = transpose(0,1,@row_vector);   # ([1],[2],[3],[4])</pre>
<a name='Reordering Dimensions'></a><h2>Reordering Dimensions</h2>
<p>An alternative form of <code>transpose</code> uses the first argument as a list ref
to specify a new order for the dimensions:</p>
<pre>  transpose [0,3,4,1,2], @arr;</pre>
<p>If some dimensions are not specified in the first argument, those
dimensions are left in their current order:</p>
<pre>  # Where @arr is a rank 5 array...
  transpose ([3], @arr) == transpose ([3,0,1,2,4], @arr);
  transpose ([0,3], @arr) == transpose ([0,3,1,2,4], @arr);</pre>
<p>This syntax allows multidimensional arrays to be reduced along any
dimension:</p>
<pre>  @sumover_1st_dim = reduce ^_ + ^_, @arr[ 0..; |i; * ];
  @sumover_3rd_dim = reduce ^_ + ^_, transpose([3],@arr)[0..; |i; * ];</pre>
<p>Note that <code>reduce</code> is from RFC 76, and <code>|i</code> is from RFC 207.</p>
<a name='Aliasing'></a><h2>Aliasing</h2>
<p><code>transpose</code> does not make a copy of the elements of its arguments; it
simply create an alias:</p>
<pre>  @row_vector = (1,2,3,4);
  @col_vector = transpose(0,1,@row_vector);  # ([1],[2],[3],[4])
  $col_vector[[0,1]] = 0;
  @row_vector == (1,0,3,4);                  # True</pre>
<a name='Optional Extra: Dimension Insert'></a><h2>Optional Extra: Dimension Insert</h2>
<p>To move a dimension and insert it before some other dimension, the
following syntax may be used:</p>
<pre>  transpose ({3=&gt;2}, @arr) == transpose ([0,1,3,2,4], @arr);</pre>
<p>which inserts dimension 3 in front of dimension 2.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>RFC 90 discusses possible approaches to implementing aliasing.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 76: Builtin: reduce</p>
<p>RFC 90: Arrays: merge() and unmerge()</p>
<p>RFC 148: Arrays: Add reshape() for multi-dimensional array reshaping</p>
<p>RFC 207: Arrays: Efficient Array Loops</p>
</div>
